doc: Migration guide to move from API Keys (PAKs) to Service Accounts #4047

filipcirtog · 2026-01-08T12:20:53Z

Description

This PR adds a migration guide to help users transition from Personal Access Keys (PAKs) to Service Accounts (SAs). The guide includes:

This guide includes:

Two dropdowns for navigation:
- Org-level SAs
- Project-level SAs
Steps for migration across three states:
1. Initial State: PAK resources only
2. Intermediate State: PAK and SA resources coexist
3. Final State: SA resources only, PAKs removed

Furthermore, examples are provided in examples/migrate_pak_to_service_account/:

Organization-level examples (org_level/):
- v1/: Initial PAK configuration
- v2/: Intermediate state with both PAK and SA resources
- v3/: Final state with SA resources only
- README.md: Usage instructions and prerequisites
Project-level examples (project_level/):
- v1/: Initial PAK configuration
- v2/: Intermediate state with both PAK and SA resources
- v3/: Final state with SA resources only
- README.md: Usage instructions and prerequisites

Note: The PR build currently fails due to a missing resource still under development. This will be then tested to confirm that everything works as expected.

We are seeking feedback on the guide content itself, specifically its clarity Thank you!

Link to any related issue(s): CLOUDP-369989

Type of change:

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR. A migration guide must be created or updated if the new feature will go in a major version.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR. A migration guide must be created or updated.
This change requires a documentation update
Documentation fix/enhancement

Required Checklist:

I have signed the MongoDB CLA
I have read the contributing guides
I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if appropriate)
I have run make fmt and formatted my code
If changes include deprecations or removals I have added appropriate changelog entries.
If changes include removal or addition of 3rd party GitHub actions, I updated our internal document. Reach out to the APIx Integration slack channel to get access to the internal document.

Further comments

manupedrozo

Good first draft!

Extra comments:

Did you follow the guide yourself to verify it works as expected?
It would be great to have supporting examples (for both org and project resources) like: migrate_atlas_user_and_atlas_users
- Note the v1/v2/v3 structure that matches this guide
- Then link to the examples guides from the tf docs

manupedrozo · 2026-01-08T12:51:59Z

docs/guides/migrate-pak-to-service-account.md

+page_title: "Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)"
+---
+
+**Note:** Migration to Service Accounts is **not required**. If you are currently using `mongodbatlas_api_key`, `mongodbatlas_api_key_project_assignment`, and `mongodbatlas_access_list_api_key` resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security, flexibility, or best practices, but existing PAK configurations will continue to work and are supported.


Not sure if flexibility is a pro of SAs vs PAKs.

Suggested change

**Note:** Migration to Service Accounts is **not required**. If you are currently using `mongodbatlas_api_key`, `mongodbatlas_api_key_project_assignment`, and `mongodbatlas_access_list_api_key` resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security, flexibility, or best practices, but existing PAK configurations will continue to work and are supported.

**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and are supported.

manupedrozo · 2026-01-08T13:03:42Z

docs/guides/migrate-pak-to-service-account.md

+
+# Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)
+
+The goal of this guide is to help users transition from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas. Service Accounts provide a more secure and flexible authentication method that eliminates the need to manage API key secrets in Terraform state.


"Service Accounts provide a more secure and flexible authentication method" - Not sure how SAs are more flexible
"Service Accounts provide a more secure and flexible authentication method that eliminates the need to manage API key secrets in Terraform state" - But we now have to manage SAs instead of PAKs, so wouldn't include this as an upside.

Take a look at the docs for the advantage of SAs over PAKs: Service accounts are the recommended method to manage authentication to the Atlas Administration API. Service accounts provide improved security over API keys by using the industry standard OAuth 2.0 protocol with the Client Credentials flow.

docs/guides/migrate-pak-to-service-account.md

manupedrozo · 2026-01-08T13:08:20Z

docs/guides/migrate-pak-to-service-account.md

+
+| PAK Resource | Service Account Resource | Notes |
+|--------------|-------------------------|-------|
+| `mongodbatlas_api_key` | `mongodbatlas_service_account` | Organization-level key/account |


manupedrozo · 2026-01-08T13:11:22Z

docs/guides/migrate-pak-to-service-account.md

+resource "mongodbatlas_api_key_project_assignment" "example" {
+  project_id = var.project_id
+  api_key_id = mongodbatlas_api_key.example.api_key_id
+  roles      = ["GROUP_OWNER", "GROUP_DATA_ACCESS_ADMIN"]


Just for clarity, wouldn't mix GROUP_OWNER with other roles since owner already contains other roles. Maybe go with ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_ONLY"].

manupedrozo · 2026-01-08T13:12:48Z

docs/guides/migrate-pak-to-service-account.md

+resource "mongodbatlas_access_list_api_key" "example" {
+  org_id     = var.org_id
+  api_key_id = mongodbatlas_api_key.example.api_key_id
+  cidr_block = "192.168.1.0/24"


Matching the alternative to avoid confusion (also in other occurrences)

Suggested change

cidr_block = "192.168.1.0/24"

cidr_block = "192.168.1.100/32"

manupedrozo · 2026-01-08T13:14:00Z

docs/guides/migrate-pak-to-service-account.md

+
+## Stage 2: Intermediate State (Both PAK and SA Resources)
+
+In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.


Suggested change

In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.

In this stage, you will add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.

manupedrozo · 2026-01-08T13:29:48Z

docs/guides/migrate-pak-to-service-account.md

+
+4. Run `terraform plan` to review the changes.
+5. Run `terraform apply` to create the Service Account resources.
+6. **Important**: Save the Service Account secret from the output. When a Service Account is created, a secret is automatically generated. The secret value is only returned once at creation time.


The output block should be added together with the service account before running apply in step 4

I think we can remove the datasources

manupedrozo

Thanks for the iteration, I think its in much better shape now!
Left more comments - Its ready to share with the docs team as well.

manupedrozo · 2026-01-09T15:33:58Z

docs/guides/migrate-pak-to-service-account.md

+## Overview
+
+Service Accounts are the recommended method to manage authentication to the Atlas Administration API. Service Accounts provide improved security over API keys by using the industry standard OAuth 2.0 protocol with the Client Credentials flow. This guide covers migrating from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas.
+
+**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and are supported.
+


Suggesting the following. Would like to get docs team input here:

Suggested change

## Overview

Service Accounts are the recommended method to manage authentication to the Atlas Administration API. Service Accounts provide improved security over API keys by using the industry standard OAuth 2.0 protocol with the Client Credentials flow. This guide covers migrating from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas.

**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and are supported.

## Overview

This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources.

**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and be supported.

Updated. Thank you!

manupedrozo · 2026-01-09T15:49:31Z

docs/guides/migrate-pak-to-service-account.md

+
+| PAK Resource | Service Account Resource | Notes |
+|--------------|-------------------------|-------|
+| `mongodbatlas_api_key` | `mongodbatlas_service_account` | Organization-level API key / Service Account |


Updated. Thank you!

manupedrozo · 2026-01-09T15:53:48Z

docs/guides/migrate-pak-to-service-account.md

+
+### Step 1: Initial State - PAK Resources Only
+
+This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):


Suggested change

This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):

Original configuration with organization-level PAK resources:

Updated. Thank you!

manupedrozo · 2026-01-09T15:55:21Z

docs/guides/migrate-pak-to-service-account.md

+
+For complete working examples, see the [organization-level migration example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_pak_to_service_account/org_level).
+
+### Step 1: Initial State - PAK Resources Only


Suggested change

### Step 1: Initial State - PAK Resources Only

### Step 1: Initial Configuration - PAK Resources Only

Updated. Thank you!

manupedrozo · 2026-01-09T15:56:42Z

docs/guides/migrate-pak-to-service-account.md

+This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):
+
+```terraform
+# Organization-level Programmatic API Key


I think we can avoid repeating "organization-level" so often. Should be clear since we are in the "Organization-Level API Keys to Service Accounts" section.

Changing the api key description to not say "for project access" may help.

Updated. Thank you!

manupedrozo · 2026-01-09T16:22:56Z

docs/guides/migrate-pak-to-service-account.md

+
+---
+
+- **Important:** The Service Account secret is only returned once at creation time. Make sure to save it securely before proceeding.


Bit out of place, I think you can remove

Updated! Thank you!

manupedrozo · 2026-01-09T16:23:55Z

docs/guides/migrate-pak-to-service-account.md

+<details>
+  <summary><span style="font-size:1.4em; font-weight:bold;">Project-Level Migration</span></summary>
+
+## Project-Level API Keys to Service Accounts


Assume same comments as for Org-level steps

Updated! Thank you!

manupedrozo · 2026-01-09T16:32:48Z

examples/migrate_pak_to_service_account/org_level/v1/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.7.0"


Need TF 1.7?

Updated! Thank you!

manupedrozo · 2026-01-09T16:34:17Z

examples/migrate_pak_to_service_account/org_level/v2/outputs.tf

+  description = "The secret value of the first secret created with the service account. Only available after initial creation."
+  value       = try(mongodbatlas_service_account.example.secrets[0].secret, null)
+  sensitive   = true
+}


Suggested change

}

}

Updated! Thank you!

manupedrozo · 2026-01-09T16:36:29Z

examples/migrate_pak_to_service_account/org_level/README.md

@@ -0,0 +1,19 @@
+# Combined Example: Organization-Level PAK → Service Account


Given that we don't have readmes with instructions in the subfolders, I suggest following this style of readme here instead: examples/migrate_atlas_user_and_atlas_users/README.md

github-actions · 2026-01-12T10:44:20Z

APIx bot: a message has been sent to Docs Slack channel

Copilot

Pull request overview

This PR adds a comprehensive migration guide to help users transition from Personal Access Keys (PAKs) to Service Accounts (SAs). The guide provides step-by-step instructions with working code examples demonstrating the migration path.

Changes:

Added migration guide documentation explaining the PAK to SA transition process
Created organization-level migration examples showing three states: PAK only, PAK+SA coexistence, and SA only
Created project-level migration examples with the same three-state approach

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/guides/migrate-pak-to-service-account.md	Main migration guide with detailed instructions and code examples for both org-level and project-level migrations
examples/migrate_pak_to_service_account/org_level/README.md	Documentation for organization-level migration example
examples/migrate_pak_to_service_account/org_level/v1/*	Initial state example showing PAK resources only at org level
examples/migrate_pak_to_service_account/org_level/v2/*	Intermediate state showing PAK and SA resources coexisting at org level
examples/migrate_pak_to_service_account/org_level/v3/*	Final state showing SA resources only at org level
examples/migrate_pak_to_service_account/project_level/README.md	Documentation for project-level migration example
examples/migrate_pak_to_service_account/project_level/v1/*	Initial state example showing PAK resources only at project level
examples/migrate_pak_to_service_account/project_level/v2/*	Intermediate state showing PAK and SA resources coexisting at project level
examples/migrate_pak_to_service_account/project_level/v3/*	Final state showing SA resources only at project level

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

examples/migrate_pak_to_service_account/org_level/v3/main.tf

examples/migrate_pak_to_service_account/org_level/README.md

Copilot

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

examples/migrate_pak_to_service_account/org_level/v3/main.tf

examples/migrate_pak_to_service_account/project_level/v1/variables.tf

examples/migrate_pak_to_service_account/project_level/v2/variables.tf

examples/migrate_pak_to_service_account/project_level/v1/variables.tf

lantoli · 2026-01-12T12:04:28Z

docs/guides/migrate-pak-to-service-account.md

+
+## Overview
+
+This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources.


nit: i'd add a clarification like to use them as authentication mechanism, see more info in: https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration

lantoli · 2026-01-12T12:06:24Z

docs/guides/migrate-pak-to-service-account.md

+
+This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources.
+
+**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and be supported.


Suggested change

**Note:** Migration to Service Accounts is **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and be supported.

**Note:** Migration to Service Accounts is recommended but **not required**. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and be supported.

updated! thank you!

EspenAlbert · 2026-01-12T13:47:38Z

docs/guides/migrate-pak-to-service-account.md

+<details>
+  <summary><span style="font-size:1.4em; font-weight:bold;">Organization-Level Migration</span></summary>
+
+## Organization-Level API Keys to Service Accounts


[nit] Would it make sense to use L3 headings for everything within this section? (Right sub headings are all L2)

updated! thank you!

erabil-mdb

LGTM! (+ small suggestion)

erabil-mdb · 2026-01-12T16:46:48Z

docs/guides/migrate-pak-to-service-account.md

+
+- **Backup your Terraform state file** before making any changes.
+- **Test the process in a non-production environment** if possible.
+- **Secrets handling** - Managing Service Accounts with Terraform will expose sensitive organizational secrets in Terraform's state. We suggest following [Terraform's best practices](https://developer.hashicorp.com/terraform/language/state/sensitive-data).


Just a suggestion for smoother reading:

Suggested change

- **Secrets handling** - Managing Service Accounts with Terraform will expose sensitive organizational secrets in Terraform's state. We suggest following [Terraform's best practices](https://developer.hashicorp.com/terraform/language/state/sensitive-data).

- Managing Service Accounts with Terraform **exposes sensitive organizational secrets** in Terraform's state. We suggest following [Terraform's best practices](https://developer.hashicorp.com/terraform/language/state/sensitive-data).

updated! thank you!

I think you missed the removal of **Secrets handling** - .
Can you also update this in the secrets rotation guide to keep consistency? Ty!

updated. thank you! will update that guide in the next doc PR (soon) as I would need to rebase this one and it is not worth the effort.

manupedrozo

Great work! Thanks for iterating and addressing comments.
Good on my side, still a few comments from others.

oarbusi · 2026-01-13T13:46:14Z

docs/guides/migrate-pak-to-service-account.md

+
+### Step 2: Intermediate State - Add Service Account Resources Alongside Existing PAK Resources
+
+Add the Service Account resources to your configuration while keeping the existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.


I think the statement "allows both authentication methods to work simultaneously" is not true, both SA and PAK exist simultaneously, but are not used simultaneously.

I was thinking on the case of using SA/PAKs as the authentication method for the MongoDB Atlas Terraform Provider, but in the cases of other applications/tools, the statement can be true. Feel free to ignore the previous comment

oarbusi · 2026-01-13T13:56:15Z

docs/guides/migrate-pak-to-service-account.md

+   terraform output -raw service_account_first_secret
+   ```
+
+4. Test your Service Account in your applications and verify that both PAK and SA authentication methods work correctly.


should we explain how that would look like in the case of switching the auth method of the TF provider from PAK to SA? something similar to https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration#programmatic-access-key warning block where we say Update your provider attributes or environment variables to use SA credentials instead of PAK credentials, then run terraform plan to verify everything works correctly.

I say this because the guide is generic in terms of the application that uses the PAK/SA, but I think the main use case we want to enable is the TF provider authentication

A previous iteration mentioned this. I suggested to remove it to avoid confusion and mention only "your applications".
For example: If the user were to change the provider credentials in this same config, they would not have permissions to re-apply as the SA has only ORG_MEMBER role.

I think it makes sense for the credentials used for provider authentication in a particular configuration to be managed outside of that same configuration.

I think we should cover the end to end case of using the new SA resource sand switching from PAK to SA as the auth method, since it's the main problem we are trying to solve by implementing these resources in TF

I am on board on including a link to the SA authentication registry page to reference how it is used but I would be careful to add it as a step here given the previous comment:

I think it makes sense for the credentials used for provider authentication in a particular configuration to be managed outside of that same configuration.

Do we know of PAK users authenticating with a PAK that is managed within the same configuration? I don't think we should be recommending this approach (can lock yourself out).

I am not saying to recommend the approach of using PAKs created in a configuration as the auth mechanism within the same configuration, but I would like to have in this guide the case of switching from PAK to SA as the auth mechanism of the TF provider, which is the main use case we want to enable, even if the SA/PAK is created in one configuration and used as auth in another. Hope that makes sense

Yes that makes sense. @filipcirtog can you mention this in the guide and include a link to the provider configuration guide with SA?
https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration

Thank you for the suggestions. I have added some notes on this. Please let me know WDY.

oarbusi

LGTM

manupedrozo · 2026-01-14T11:15:39Z

docs/guides/migrate-pak-to-service-account.md

-This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources.
+This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources managed by Terraform.
+
+**Important:** The steps in this guide are for migrating Terraform-managed PAK and SA resources (e.g., `mongodbatlas_api_key`, `mongodbatlas_service_account`). This guide does **not** cover switching the Terraform provider authentication method from PAK to SA. For information on configuring the provider to authenticate using Service Accounts instead of Programmatic Access Keys, see the [Provider Configuration guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration).


Its a bit confusing that we mention here that This guide does **not** cover switching the Terraform provider authentication method but then we have a ## Switching Terraform Provider Authentication section.
I think we can remove this or change the wording to something like: "If you are looking to change the provider authentication method, refer to ..."

updated. thanks!

manupedrozo · 2026-01-14T11:20:01Z

docs/guides/migrate-pak-to-service-account.md

+
+---
+
+## Switching Terraform Provider Authentication


Suggested change

## Switching Terraform Provider Authentication

## Switching the Provider Authentication Method

updated. thanks!

manupedrozo · 2026-01-14T11:22:08Z

docs/guides/migrate-pak-to-service-account.md

+
+For detailed instructions on configuring Service Account authentication for the provider, see the [Provider Configuration guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration).
+
+**Note:** The Service Account used for provider authentication can be created in a separate Terraform configuration or managed outside of Terraform. It's recommended to manage provider authentication credentials separately from the resources they manage to avoid potential lockout scenarios.


Suggested change

**Note:** The Service Account used for provider authentication can be created in a separate Terraform configuration or managed outside of Terraform. It's recommended to manage provider authentication credentials separately from the resources they manage to avoid potential lockout scenarios.

**Note:** The Service Account used for provider authentication should be created in a separate Terraform configuration or managed outside of Terraform. It is recommended to manage provider authentication credentials separately from the resources they manage to avoid potential lockout scenarios.

updated. thanks!

manupedrozo · 2026-01-14T11:23:03Z

docs/guides/migrate-pak-to-service-account.md

+
+## Switching Terraform Provider Authentication
+
+After migrating your Terraform-managed resources from PAK to SA, you may also want to switch the Terraform provider authentication method from PAK to SA. This is a common use case for migrating to Service Accounts.


Suggested change

After migrating your Terraform-managed resources from PAK to SA, you may also want to switch the Terraform provider authentication method from PAK to SA. This is a common use case for migrating to Service Accounts.

After migrating your Terraform-managed resources from PAK to SA, you may also want to switch the Terraform provider authentication method.

updated. thanks!

…ev' into CLOUDP-352932-service-accounts-dev-migration-guide

…service-accounts-dev-migration-guide

oarbusi · 2026-01-15T09:09:00Z

Thanks for addressing the comments! LGTM

examples/migrate_pak_to_service_account/org_level/README.md

manupedrozo · 2026-01-15T09:59:26Z

examples/migrate_pak_to_service_account/org_level/README.md

+service_account_name        = "example-service-account"
+secret_expires_after_hours = 2160                                # 90 days


Suggested change

service_account_name = "example-service-account"

secret_expires_after_hours = 2160 # 90 days

service_account_name = "example-service-account"

secret_expires_after_hours = 2160 # 90 days

updated! thanks!

examples/migrate_pak_to_service_account/project_level/README.md

manupedrozo · 2026-01-15T10:01:09Z

examples/migrate_pak_to_service_account/project_level/README.md

+```terraform
+project_service_account_name        = "example-project-service-account"
+secret_expires_after_hours = 2160                                # 90 days
+```


Suggested change

```terraform

project_service_account_name = "example-project-service-account"

secret_expires_after_hours = 2160 # 90 days

```

```terraform

project_service_account_name = "example-project-service-account"

secret_expires_after_hours = 2160 # 90 days

updated! thanks!

…service-accounts-dev-migration-guide

Copilot

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

* feat: Adds the mongodbatlas_service_account resource and data-source/s (#4018) * Add mongodbatlas_service_account_secret resource and datasource (#4027) * feat: Add mongodbatlas_service_account_project_assignment resource and datasources (#4030) * Add service_account_project_assignment test with multiple assignments (#4032) * Add service_account_access_list_entry resource and datasources (#4037) * Add project_service_account resource and datasources (#4038) * doc: Add service_account resource and datasources docs (#4039) * Add service_account_project_assignment resource and datasources docs (#4040) * feat: Add project_service_account_secret resource and datasource (#4041) * Service Account secret rotation guide (#4050) * doc: Add service_account_secret & project_service_account_secret resource and datasource docs (#4051) * feat: Add `project_service_account_access_list_entry` resource and datasources (#4060) * project_service_account_access_list_entry resource, data source and plural data source implementation * add changelog and CI tests * fix test * address PR comments * Bump sdk in dev branch (#4069) * doc: Add Documentation for `mongodbatlas_service_account_access_list_entry` and `mongodbatlas_project_service_account_access_list_entry` resources, singular data-sources, and plural data-sources (#4071) * doc additions * ensure consistency across docs * improve prerequisites wording * ensure format consistency * fix mutation fail * fix ci * fix fmt * fix mutation fail * docs improvements * fix examples fmt * fix mutation fail * feedback improvements * doc: Add `project_service_account` resource and datasources docs (#4066) * doc additions * docs improvements * group important notes togather * docs improvements * feedback improvements * wording improvements * doc: Migration guide to move from API Keys (PAKs) to Service Accounts (#4047) * add migration guide * refactoring + examples * remove boilerplate text * nit: ensure consistency between the org and project guides * address PR comments * ensure EOL consistency * address PR comment * address copilot consistency comments * ensure spacing consistency * consistency fixes * implement PR suggestions * nit * addition of terraform auth note * feedback improvements * update secret handling guide with working improvement * format improvements * consistency improvements * fix: Ensure consistency between `service_account_secret` and `project_service_account_secret` resources and DSs (#4081) * consistency improvements * feedback improvements * chore: Add flag to overwrite lists state in autogen unmarshalling (#4086) * Test runner reorder --------- Co-authored-by: Filip Cirtog <filip.cirtog@mongodb.com> Co-authored-by: svc-apix-bot <svc-api-experience-integrations-escalation@mongodb.com>

add migration guide

6673a65

filipcirtog changed the base branch from master to CLOUDP-352932-service-accounts-dev January 8, 2026 12:21

filipcirtog changed the title ~~doc: PAK's to SA migration guide~~ doc: Migration guide to move from API Keys (PAKs) to Service Accounts Jan 8, 2026

manupedrozo reviewed Jan 8, 2026

View reviewed changes

filipcirtog added 3 commits January 9, 2026 15:22

refactoring + examples

abbcbc5

remove boilerplate text

d861ec5

nit: ensure consistency between the org and project guides

f71aec5

manupedrozo reviewed Jan 9, 2026

View reviewed changes

filipcirtog added 3 commits January 12, 2026 10:54

address PR comments

94d9269

ensure EOL consistency

a0d4586

address PR comment

785a98e

filipcirtog marked this pull request as ready for review January 12, 2026 10:44

filipcirtog requested review from a team as code owners January 12, 2026 10:44

Copilot AI review requested due to automatic review settings January 12, 2026 10:44

Copilot AI reviewed Jan 12, 2026

View reviewed changes

examples/migrate_pak_to_service_account/org_level/v3/main.tf Outdated Show resolved Hide resolved

examples/migrate_pak_to_service_account/org_level/README.md Outdated Show resolved Hide resolved

address copilot consistency comments

dc6053d

filipcirtog requested a review from Copilot January 12, 2026 10:51

Copilot AI reviewed Jan 12, 2026

View reviewed changes

filipcirtog added 2 commits January 12, 2026 11:55

ensure spacing consistency

5939987

consistency fixes

647528f

lantoli reviewed Jan 12, 2026

View reviewed changes

EspenAlbert reviewed Jan 12, 2026

View reviewed changes

erabil-mdb approved these changes Jan 12, 2026

View reviewed changes

manupedrozo approved these changes Jan 12, 2026

View reviewed changes

oarbusi reviewed Jan 13, 2026

View reviewed changes

oarbusi approved these changes Jan 13, 2026

View reviewed changes

filipcirtog added 3 commits January 13, 2026 17:45

implement PR suggestions

2d95fdd

nit

74cc59f

addition of terraform auth note

766060a

manupedrozo reviewed Jan 14, 2026

View reviewed changes

filipcirtog added 4 commits January 14, 2026 12:49

feedback improvements

9a96afa

Merge remote-tracking branch 'origin/CLOUDP-352932-service-accounts-d…

e9f3c55

…ev' into CLOUDP-352932-service-accounts-dev-migration-guide

update secret handling guide with working improvement

52d2486

Merge branch 'CLOUDP-352932-service-accounts-dev' into CLOUDP-352932-…

dd6acfc

…service-accounts-dev-migration-guide

manupedrozo reviewed Jan 15, 2026

View reviewed changes

format improvements

0fdf9ee

marcosuma approved these changes Jan 15, 2026

View reviewed changes

filipcirtog added 2 commits January 16, 2026 18:19

Merge branch 'CLOUDP-352932-service-accounts-dev' into CLOUDP-352932-…

23927a3

…service-accounts-dev-migration-guide

consistency improvements

8819abd

filipcirtog requested a review from Copilot January 19, 2026 08:53

Copilot AI reviewed Jan 19, 2026

View reviewed changes

filipcirtog merged commit 88668b5 into CLOUDP-352932-service-accounts-dev Jan 19, 2026
47 checks passed

filipcirtog deleted the CLOUDP-352932-service-accounts-dev-migration-guide branch January 19, 2026 09:07


		# Migration Guide: Programmatic API Keys (PAKs) to Service Accounts (SAs)

		The goal of this guide is to help users transition from Programmatic API Keys (PAKs) to Service Accounts (SAs) in MongoDB Atlas. Service Accounts provide a more secure and flexible authentication method that eliminates the need to manage API key secrets in Terraform state.

	\| `mongodbatlas_api_key` \| `mongodbatlas_service_account` \| Organization-level key/account \|
	\| `mongodbatlas_api_key` \| `mongodbatlas_service_account` \| API key / Service Account \|

	cidr_block = "192.168.1.0/24"
	cidr_block = "192.168.1.100/32"


		## Stage 2: Intermediate State (Both PAK and SA Resources)

		In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.

	In this stage, you'll add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.
	In this stage, you will add Service Account resources alongside your existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.


		### Step 1: Initial State - PAK Resources Only

		This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):

	This is your starting configuration with organization-level PAK resources (org PAK + assignment to project + access list entry):
	Original configuration with organization-level PAK resources:


		For complete working examples, see the [organization-level migration example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_pak_to_service_account/org_level).

		### Step 1: Initial State - PAK Resources Only

	### Step 1: Initial State - PAK Resources Only
	### Step 1: Initial Configuration - PAK Resources Only


		---

		- Important: The Service Account secret is only returned once at creation time. Make sure to save it securely before proceeding.

		@@ -0,0 +1,19 @@
		# Combined Example: Organization-Level PAK → Service Account


		## Overview

		This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources.


		This guide explains how to migrate from Programmatic API Key (PAK) resources to Service Account (SA) resources.

		Note: Migration to Service Accounts is not required. If you are currently using API Key resources, you may continue to do so. This guide is for users who wish to adopt Service Accounts for greater security or best practices, but existing PAK configurations will continue to work and be supported.

	- Secrets handling - Managing Service Accounts with Terraform will expose sensitive organizational secrets in Terraform's state. We suggest following [Terraform's best practices](https://developer.hashicorp.com/terraform/language/state/sensitive-data).
	- Managing Service Accounts with Terraform exposes sensitive organizational secrets in Terraform's state. We suggest following [Terraform's best practices](https://developer.hashicorp.com/terraform/language/state/sensitive-data).


		### Step 2: Intermediate State - Add Service Account Resources Alongside Existing PAK Resources

		Add the Service Account resources to your configuration while keeping the existing PAK resources. This allows both authentication methods to work simultaneously, enabling you to test Service Accounts before removing PAKs.

	## Switching Terraform Provider Authentication
	## Switching the Provider Authentication Method


		For detailed instructions on configuring Service Account authentication for the provider, see the [Provider Configuration guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration).

		Note: The Service Account used for provider authentication can be created in a separate Terraform configuration or managed outside of Terraform. It's recommended to manage provider authentication credentials separately from the resources they manage to avoid potential lockout scenarios.


		## Switching Terraform Provider Authentication

		After migrating your Terraform-managed resources from PAK to SA, you may also want to switch the Terraform provider authentication method from PAK to SA. This is a common use case for migrating to Service Accounts.

		service_account_name = "example-service-account"
		secret_expires_after_hours = 2160 # 90 days

doc: Migration guide to move from API Keys (PAKs) to Service Accounts #4047

doc: Migration guide to move from API Keys (PAKs) to Service Accounts #4047

Conversation

filipcirtog commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change:

Required Checklist:

Further comments

Uh oh!

manupedrozo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manupedrozo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

filipcirtog commented Jan 8, 2026 •

edited

Loading